.\" $Id: PAPI_get_executable_info.3,v 1.13 2004/10/02 18:23:00 terpstra Exp $
.TH PAPI_get_executable_info 3 "September, 2004" "PAPI Programmer's Reference" PAPI

.SH NAME
PAPI_get_executable_info \- get the executable's address space info

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "const PAPI_exe_info_t *PAPI_get_executable_info(void);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI "PAPIF_get_exe_info(C_STRING " fullname," C_STRING "  name,
.BI "       C_LONG_LONG "  text_start, " C_LONG_LONG "  text_end, 
.BI "       C_LONG_LONG "  data_start, " C_LONG_LONG "  data_end,
.BI "       C_LONG_LONG "  bss_start, "  C_LONG_LONG "  bss_end, " C_INT " check)
.fi

.SH DESCRIPTION
In C, this function returns a pointer to a structure containing information about
the current program. In Fortran, the fields of the structure are returned explicitly.

.SH ARGUMENTS
The following arguments are implicit in the structure returned by the C function,
or explicitly returned by Fortran.
.LP
.I fullname
--  fully qualified path + filename of the executable
.LP
.I name
--  filename of the executable with no path information
.LP
.I text_start, text_end
--  Start and End addresses of program text segment
.LP
.I data_start, data_end
--  Start and End addresses of program data segment
.LP
.I bss_start, bss_end
--  Start and End addresses of program bss segment

.SH RETURN VALUES
On success, the C function returns a non-NULL pointer, 
and the Fortran function returns 
.B PAPI_OK.
 On error, NULL is returned by the C function, 
and a non-zero error code is returned by the Fortran function.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.

.SH EXAMPLE
.LP
.nf
.if t .ft CW
const PAPI_exe_info_t *prginfo = NULL;
	
if ((prginfo = PAPI_get_executable_info()) == NULL)
  exit(1);

printf("Path+Program: %s\n",exeinfo->fullname);
printf("Program: %s\n",exeinfo->address_info.name);
printf("Text start: %p, Text end: %p\n",exeinfo->address_info.text_start,exeinfo->address_info.text_end);
printf("Data start: %p, Data end: %p\n",exeinfo->address_info.data_start,exeinfo->address_info.data_end);
printf("Bss start: %p, Bss end: %p\n",exeinfo->address_info.bss_start,exeinfo->address_info.bss_end);
.if t .ft P
.fi

.SH DATA STRUCTURES
.LP
.nf
.if t .ft CW
   typedef struct _papi_address_map {
      char name[PAPI_HUGE_STR_LEN];
      caddr_t text_start;       /* Start address of program text segment */
      caddr_t text_end;         /* End address of program text segment */
      caddr_t data_start;       /* Start address of program data segment */
      caddr_t data_end;         /* End address of program data segment */
      caddr_t bss_start;        /* Start address of program bss segment */
      caddr_t bss_end;          /* End address of program bss segment */
   } PAPI_address_map_t;

   typedef struct _papi_program_info {
      char fullname[PAPI_HUGE_STR_LEN];  /* path+name */
      PAPI_address_map_t address_info;
   } PAPI_exe_info_t;
.if t .ft P
.fi

.SH BUGS
Only the
.I text_start
and
.I text_end
fields are filled on every architecture.

.SH SEE ALSO
.BR PAPI_get_hardware_info "(3), "
.BR PAPI_get_opt "(3)"
